<HTML>
<HEAD>
<TITLE>TSP (audio) - CopyAudio</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFACD">
<H2>CopyAudio</H2>
<HR>
<H4>Routine</H4>
<DL>
<DT>
CopyAudio [options] AFileA AFileB ... AFileO
</DL>
<H4>Purpose</H4>
<DL>
<DT>
Copy audio files (combine/concatenate, scale and shift data)
</DL>
<H4>Description</H4>
This program copies samples from one or more input audio files to an output
audio file.  The samples in the output file are linear combinations of the
samples in the different channels in the input files.  In the combine mode,
data from multiple input files is combined.  In the concatenate mode, data
from multiple input files is concatenated.
<P>
The output consists of linear combinations of the input data channels.  For
instance output channel A can be formed as the average of input channel A and
input channel B.  For multichannel data, the data is organized into sample
frames, with samples from individual channels making up a frame.
<P>
Sample limits may be specified for the input data.  The same sample limits
apply to each channel in a file.  Samples in the file are numbered from zero.
Negative sample limits may be specified; the samples corresponding to
negative indices have zero values.  Similarly, sample limits beyond the
end-of-file may be specified; samples beyond the end-of-file are assumed to
have zero values.
<P>
The combine and concatenate modes differ in how they treat multiple input
files.  For the combine mode, if there is more than one input file, channels
assignments cross between input files.  Consider two input files, with the
first having 3 channels, and the second having 2 channels.  The channels are
labelled A to E, with channels A, B and C coming from the first input file
and channels D and E coming from the second input file.  For the combine
mode, a single sample limits specification applies to all input files.  The
default sample limits correspond to the length of the longest input file.
If necessary, the data from the input files is padded with zeros to a common
length before combining.
<P>
In the concatenate mode, the data in the input files is concatenated.  The
number of channels in each input file must be the same.  For the concatenate
mode, sample limits can be specified for each input file.  The default sample
limits for an input file correspond to the length of that file.
<P>
For fixed point data, the data is normalized to the range -1 to +1.  This
normalization becomes important when files with different data formats are
combined.
<P>
The default data format for the output file is chosen according to a data
format promotion rule based on the data types of the input files.  For single
input files, the output data format will be the same as the input data format
as long as that data format is compatible with the output file type.
<H4>Options</H4>
<DL>
<DT>
Input file names: AFileA AFileB ...:
<DD>
The environment variable AUDIOPATH specifies a list of directories to be
searched for the input audio file(s).  Specifying "-" as the input file
name indicates that input is from standard input.
<DT>
Output file name: AFileO:
<DD>
The last file name is the output file.  Specifying "-" as the output file
name indicates that output is to be written to standard output.  If the
output file type is not explicitly given (-F option), the extension of
the output file name is used to determine the file type.
<PRE>
  ".au"   - AU audio file
  ".wav"  - WAVE file
  ".aif"  - AIFF sound file
  ".afc"  - AIFF-C sound file
  ".raw"  - Headerless file (native byte order)
  ".txt"  - Headerless file (text data)
</PRE>
<DT>
-c, --combine
<DD>
Use the combine mode for multiple input files (default)
<DT>
-C, --concatenate
<DD>
Use the concatenate mode for multiple input files
<DT>
-g GAIN, --gain=GAIN
<DD>
A gain factor applied to the data from the input files.  This gain
applies to all channels in a file and is applied in addition to the
channel scaling factors.  The gain value can be given as a real number
(e.g., "0.003") or as a ratio (e.g., "1/256"). This option may be
given more than once.  This option may be given more than once.  Each
invocation applies to the input files that follow the option.
<DT>
-l L:U, --limits=L:U
<DD>
Sample limits for the input files (numbered from zero).  For the combine
mode, the default sample limits correspond to the limits of the longest
input audio file.  For the concatenate mode, this option may be given
more than once.  Each invocation applies to the input files that follow
the option.  The specification ":" means the entire file; "L:" means from
sample L to the end; ":U" means from sample 0 to sample U; "N" means from
sample 0 to sample N-1.
<DT>
-t FTYPE, --type=FTYPE
<DD>
Input audio file type.  In the default automatic mode, the input file
type is determined from the file header.  For input from a non-random
access file (e.g. a pipe), the input file type can be explicitly
specified to avoid the lookahead used to read the file header.  This
option can be specified more than once.  Each invocation applies to the
input files that follow the option.  See the description of the
environment variable AF_FILETYPE below for a list of file types.
<DT>
-P PARMS, --parameters=PARMS
<DD>
Parameters to be used for headerless input files.  This option may be
given more than once.  Each invocation applies to the input files that
follow the option.  See the description of the environment variable
AF_NOHEADER below for the format of the parameter specification.
<DT>
-s SFREQ, --srate=SFREQ
<DD>
Sampling frequency for the output file, default from the input audio
file(s).  This option only changes the sampling frequency field in the
output header; the audio data itself is unaffected.
<DT>
-n NSAMPLE, --number_samples=NSAMPLE
<DD>
Number of samples (per channel) for the output file.
<DT>
-cA CGAINS, --chanA=CGAINS
<DD>
Channel scaling  factors for output channel A.  The output data for the
specified output channel is created by adding scaled samples from the
specified input channels.  The default is to have each output channel
equal to the corresponding input channel.  Input channels are labelled
A, B, C, ... , R, S, T.  The channel scaling factor string takes the
form
<PRE>
  [+|-] [gain *] chan +|- [gain *] chan ... +|- offset
</PRE>
where chan is A through L.  The gains can be expressed as ratios, i.e.
of the form "n/m".  The offset is in normalized units, where an offset
of one corresponds to full scale.  Note that that the character "*" is
a special character to Unix shells and should appear only within quotes
to prevent the shell from interpreting it.
<DT>
-cB CGAINS, --chanB=CGAINS
<DD>
Channel scaling factors for output channel B.
<PRE>
  ...
</PRE>
<DT>
-cL CGAINS, --chanL=CGAINS
<DD>
Channel scaling factors for output channel L.
<DT>
-F FTYPE, --file_type=FTYPE
<DD>
Output file type.  If this option is not specified, the file type is
determined by the output file name extension.
<PRE>
  "AU" or "au"             - AU audio file
  "WAVE" or "wave"         - WAVE file
  "WAVE-NOEX" or "wave-noex" - WAVE file (no extensible data)
  "AIFF-C" "aiff-c"        - AIFF-C sound file
  "AIFF" or "aiff"         - AIFF sound file
  "noheader" or "noheader_native" - Headerless file (native byte
                             order)
  "noheader_swap"          - Headerless file (byte swapped)
  "noheader_big-endian"    - Headerless file (big-endian byte
                             order)
  "noheader_little-endian" - Headerless file (little-endian byte
                             order)
</PRE>
<DT>
-D DFORMAT, --data_format=DFORMAT
<DD>
Data format for the output file.
<PRE>
  "mu-law8"   - 8-bit mu-law data
  "A-law8"    - 8-bit A-law data
  "unsigned8" - offset-binary 8-bit integer data
  "integer8"  - two's-complement 8-bit integer data
  "integer16" - two's-complement 16-bit integer data
  "integer24" - two's-complement 24-bit integer data
  "integer32" - two's-complement 32-bit integer data
  "float32"   - 32-bit floating-point data
  "float64"   - 64-bit floating-point data
  "text"      - text data
</PRE>
The data formats available depend on the output file type.
AU audio files:
<PRE>
  mu-law, A-law, 8/16/24/32-bit integer, 32/64-bit float
</PRE>
WAVE files:
<PRE>
  mu-law, A-law, offset-binary 8-bit integer, 16/24/32-bit integer,
  32/64-bit float
</PRE>
AIFF-C sound files:
<PRE>
  mu-law, A-law, 8/16/24/32-bit integer, 32/64-bit float
</PRE>
AIFF sound files:
<PRE>
  8/16/24/32-bit integer
</PRE>
Headerless files:
<PRE>
  all data formats
</PRE>
Optionally, the number of "valid" bits may be specified as a qualifier
to the data format, e.g. "integer16/12".  The number of valid bits is
for informational purposes only.
<DT>
-S SPEAKERS, --speakers=SPEAKERS
<DD>
Mapping of output channels to speaker positions.  The spacial positions
of the loudspeakers are specified as a list of white-space separated
locations from the list below.
<PRE>
  "FL"  - Front Left
  "FR"  - Front Right
  "FC"  - Front Center
  "LF"  - Low Frequency
  "BL"  - Back Left
  "BR"  - Back Right
  "FLC" - Front Left of Center
  "FRC" - Front Right of Center
  "BC"  - Back Center
  "SL"  - Side Left
  "SR"  - Side Right
  "TC"  - Top Center
  "TFL" - Top Front Left
  "TFC" - Top Front Center
  "TFR" - Top Front Right
  "TBL" - Top Back Lefty
  "TBC" - Top Back Center
  "TBR" - Top Back Right
  "-"   - none
</PRE>
A speaker position can be associated with only one channel.  In the case
of WAVE files, the subset of spacial positions must appear in the order
given above.
<DT>
-I INFO, --info=INFO
<DD>
Audio file information string for the output file.
<DT>
-h, --help
<DD>
Print a list of options and exit.
<DT>
-v, --version
<DD>
Print the version number and exit.
</DL>
<P>
This program allows direct specification of the gains for 12 output channels
and 20 input channels.  The program can handle larger numbers of channels
for the case that the input channels are in a one-to-one correspondence with
the output channels.  A gain factor applying to all channels can be specified
with the -g or --gain option.
<P>
By default, the output file contains a standard audio file information
string.
<PRE>
  Standard Audio File Information:
     date: 2001-01-25 19:19:39 UTC    date
     program: CopyAudio               program name
</PRE>
This information can be changed with the information string which is
specified as one of the command line options.  Structured information records
should adhere to the above format with a named field terminated by a colon,
followed by numeric data or text.  Comments can follow as unstructured
information.
<PRE>
  Record delimiter: Newline character or the two character escape
      sequence "\" + "n".
  Line delimiter: Within records, lines are delimiteded by a carriage
      control character, the two character escape sequence "\" + "r",
      or the two character sequence "\" + newline.
</PRE>
If the information string starts with a record delimiter, the header
information string is appended to the standard header information.  If not,
the user supplied header information string appears alone.
<H4>Examples</H4>
<DL>
<DT>
 1: File convert.
<DD>
Copy audio file abc.au to abc.wav.  The output audio file is a WAVE file
with the same data type (if possible) as the input file.  The number of
channels in the output file is the same as the number of channels in the
input file.
<PRE>
  CopyAudio abc.au abc.wav
</PRE>
<DT>
 2: Concatenate audio data.
<DD>
Form a audio file which is the concatenation of the data from two input
files.
<PRE>
  CopyAudio -C abc1.au abc2.au abc12.au
</PRE>
<DT>
 3: Difference between values.
<DD>
Create an output audio file in which each sample is the difference
between corresponding samples in two single channel input audio files.
<PRE>
  CopyAudio --chanA=A-B abc1.au abc2.au diff.au
</PRE>
<DT>
 4: Scale sample values.
<DD>
Scale the samples in the input single-channel file by 0.5.
<PRE>
  CopyAudio --gain=1/2 abc.au scaled.au
</PRE>
The same result can be obtained by specifying the gain for the (single)
output channel.
<PRE>
  CopyAudio --chanA="0.5*A" abc.au scaled.au
</PRE>
<DT>
 5: Byte-swap data values.
<DD>
Let the input audio file be headerless and contain 16-bit data.  Create a
headerless audio file with byte-swapped data.
<PRE>
  CopyAudio -P integer16 -F noheader_swap abc.au swap.au
</PRE>
<DT>
 6: Extract samples.
<DD>
Extract samples 1000 to 1999 inclusive from the input audio file. The
output audio file will have 1000 samples.
<PRE>
  CopyAudio -l 1000:1999 abc.au out.au
</PRE>
<DT>
 7: Create a stereo file.
<DD>
Form a stereo (2-channel) audio file from two single channel audio files.
<PRE>
  CopyAudio abc1.wav abc2.wav -S "FL FR" stereo.wav
</PRE>
<DT>
 8: Add a dc value to a file.
<DD>
If the input file has a mean value of 8.63/32768, the output file will
have a zero mean after adding -8.63/32768 to each sample.
<PRE>
  CopyAudio --chanA="A-8.63/32768" abc.au zeromean.au
</PRE>
</DL>
<H4>Environment variables</H4>
<DL>
<DT>
AF_FILETYPE:
</DL>
This environment variable defines the input audio file type.  In the default
mode, the input file type is determined from the file header.
<PRE>
  "auto"       - determine the input file type from the file header
  "AU" or "au" - AU audio file
  "WAVE" or "wave" - WAVE file
  "AIFF" or "aiff" - AIFF or AIFF-C sound file
  "noheader"   - headerless (non-standard or no header) audio file
  "SPHERE"     - NIST SPHERE audio file
  "ESPS"       - ESPS sampled data feature file
  "IRCAM"      - IRCAM soundfile
  "SPPACK"     - SPPACK file
  "INRS"       - INRS-Telecom audio file
  "SPW"        - Comdisco SPW Signal file
  "CSL" or "NSP" - CSL NSP file
  "text"       - Text audio file
</PRE>
<P>
<DL>
<DT>
AF_NOHEADER:
</DL>
This environment variable defines the data format for headerless or
non-standard input audio files.  The string consists of a list of parameters
separated by commas.  The form of the list is
<PRE>
  "Format, Start, Sfreq, Swapb, Nchan, ScaleF"
</PRE>
The list can be shortened and elements skipped (nothing between adjacent
commas.  The missing parameters take on default values.
<DL>
<DT>
Format: File data format
<DD>
<PRE>
 "undefined" - Headerless files will be rejected
 "mu-law8"   - 8-bit mu-law data
 "A-law8"    - 8-bit A-law data
 "unsigned8" - offset-binary 8-bit integer data
 "integer8"  - two's-complement 8-bit integer data
 "integer16" - two's-complement 16-bit integer data
 "integer24" - two's-complement 24-bit integer data
 "integer32" - two's-complement 32-bit integer data
 "float32"   - 32-bit floating-point data
 "float64"   - 64-bit floating-point data
 "text"      - text data
</PRE>
<DT>
Start: byte offset to the start of data (integer value)
<DT>
Sfreq: sampling frequency in Hz (floating point number)
<DT>
Swapb: Data byte swap parameter
<DD>
<PRE>
 "native"        - no byte swapping
 "little-endian" - file data is in little-endian byte order
 "big-endian"    - file data is in big-endian byte order
 "swap"          - swap the data bytes as the data is read
</PRE>
<DT>
Nchan: number of channels
<DD>
The data consists of interleaved samples from Nchan channels
<DT>
ScaleF: Scale factor
<DD>
<PRE>
 "default" - Scale factor chosen appropriate to the type of data. The
    scaling factors shown below are applied to the data in the file.
    8-bit mu-law:    1/32768
    8-bit A-law:     1/32768
    8-bit integer:   128/32768
    16-bit integer:  1/32768
    24-bit integer:  1/(256*32768)
    32-bit integer:  1/(65536*32768)
    float data:      1
 "&lt;number or ratio&gt;" - Specify the scale factor to be applied to
    the data from the file.
</PRE>
</DL>
The default values for the audio file parameters correspond to the following
string.
<PRE>
  "undefined, 0, 8000., native, 1, default"
</PRE>
<P>
<DL>
<DT>
AUDIOPATH:
</DL>
This environment variable specifies a list of directories to be searched when
opening the input audio files.  Directories in the list are separated by
colons (semicolons for Windows).
<H4>Author / version</H4>
P. Kabal / v6r0  2003-05-08
<P>
<HR>
Main Index <A HREF="AFsp.html">AFsp</A>
</BODY>
</HTML>
